Release 10.1A: OpenEdge Development:
Progress Dynamics Advanced Development

Property management

The Session Manager on the client maintains a temp-table of property values representing context information needed by the client. For values stored in the temp-table, no server call is necessary to retrieve a value. This temp-table is initialized at session start-up with values for the standard client properties such as user ID and login company. These values are then passed to the server if they are also needed there. Only properties that are solely maintained on the client can be cached locally on the client in this way, even though their values can be read server-side. If it is possible for code to modify the property value on the server, then the client temp-table cannot have the property value, and the client must always redirect the request for the property to the server.

The Session Manager is also used for client-side properties that do not need to be reflected on the server. For these properties, the value is only managed on the client. This can be a useful and efficient mechanism for temporary storage of information between program calls, as the Session Manager is always initiated at the start of every session and runs in every client session.

If there is no AppServer connection, then the server version of the Session Manager is run on the client. In this case, all properties are cached in the temp-table and the context database table is not used.

In addition to the many standard properties already defined, application code can define and store any additional properties just by passing them to the Session Manager. There are two simple calls to do this:

getPropertyList (INPUT pcPropertyList AS CHARACTER, INPUT plSessionOnly AS LOGICAL) RETURNS CHARACTER — This function retrieves the specified property values from the local temp-table if they’re available. If they are not available in the temp-table, then the function makes a call to the AppServer to check the context database table. If the Session-Only flag is set to YES and the request is made on the client side, then the context database table is not checked. The input property list can also be a comma-separated list of property names. The return value is a CHR(3)-delimited list of values. It’s advisable to get (and set) as many values together as possible if they must be retrieved from the server, to minimize AppServer traffic, as shown:

DYNAMIC-FUNCTION(“getPropertyList”:U IN gshSessionManager ( INPUT pcPropertyList, INPUT plSessionOnly ).

SetPropertyList (INPUT pcPropertyList AS CHARACTER, INPUT pcPropertyValues AS CHARACTER, INPUT plSessionOnly AS LOGICAL) RETURNS LOGICAL — This function sets the specified property values in the local temp-table if it is run on the client side. If it is invoked on the client and the Session-Only flag is set to NO, then the property is also set in the context database table for use by the remote session, as shown:

DYNAMIC-FUNCTION(“setPropertyList”:U IN gshSessionManager ( INPUT pcPropertyList, INPUT pcPropertyValues, INPUT plSessionOnly ).

Here are a few things to keep in mind when you use these functions:

As noted, you can define a new property just by using it in a call to setPropertyList. For this reason, it is important to check for spelling errors in calls to the function, because an attempt to set a property using the wrong name silently creates a new property with the wrong name and sets its value instead.
Always consider which property values are needed on the client and which are needed on the server. You can use the property functions and the context table to store any information that might be needed elsewhere in the application. If it is needed only by other client-side code, then always set the Session-Only flag to YES. In this way, the value is stored only in the client temp-table. If business logic on the server could use or set the value, then you must set the Session-Only flag to NO and consider that every time you set the property, or retrieve it from the client, you incur an AppServer hit.
To set a property value to null, use an empty string (“”), not the Progress Unknown value (?).